home *** CD-ROM | disk | FTP | other *** search
- <?xml version='1.0' encoding='UTF-8' ?>
- <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
- <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-
- <!--
- Copyright 2003-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
- -->
-
- <manualpage metafile="dbmmanage.xml.meta">
- <parentdocument href="./">Programs</parentdocument>
-
- <title>dbmmanage - Manage user authentication files in DBM format</title>
-
- <summary>
- <p><code>dbmmanage</code> is used to create and update the DBM format files
- used to store usernames and password for basic authentication of HTTP users.
- Resources available from the Apache HTTP server can be restricted to just
- the users listed in the files created by <code>dbmmanage</code>. This
- program can only be used when the usernames are stored in a DBM file. To
- use a flat-file database see <a href="htpasswd.html">htpasswd</a>.</p>
-
- <p>This manual page only lists the command line arguments. For details of
- the directives necessary to configure user authentication in
- <a href="httpd.html">httpd</a> see the httpd manual, which is part of
- the Apache distribution or can be found at <a
- href="http://httpd.apache.org/">http://httpd.apache.org/</a>.</p>
- </summary>
- <seealso><a href="httpd.html">httpd</a></seealso>
- <seealso><module>mod_auth_dbm</module></seealso>
-
- <section id="synopsis"><title>Synopsis</title>
- <p><code><strong>dbmmanage</strong> [ <var>encoding</var> ]
- <var>filename</var> add|adduser|check|delete|update
- <var>username</var>
- [ <var>encpasswd</var>
- [ <var>group</var>[,<var>group</var>...]
- [ <var>comment</var> ] ] ]</code></p>
-
- <p><code><strong>dbmmanage</strong> <var>filename</var>
- view [ <var>username</var> ]</code></p>
-
- <p><code><strong>dbmmanage</strong> <var>filename</var> import</code></p>
- </section>
-
- <section id="options"><title>Options</title>
- <dl>
- <dt><code><var>filename</var></code></dt>
- <dd>The filename of the DBM format file. Usually without the extension
- <code>.db</code>, <code>.pag</code>, or <code>.dir</code>.</dd>
-
- <dt><code><var>username</var></code></dt>
- <dd>The user for which the operations are performed. The <var>username</var>
- may not contain a colon (<code>:</code>).</dd>
-
- <dt><code><var>encpasswd</var></code></dt>
- <dd>This is the already encrypted password to use for the
- <code>update</code> and <code>add</code> commands. You may use a hyphen
- (<code>-</code>) if you want to get prompted for the password, but fill
- in the fields afterwards. Additionally when using the <code>update</code>
- command, a period (<code>.</code>) keeps the original password
- untouched.</dd>
-
- <dt><code><var>group</var></code></dt>
- <dd>A group, which the user is member of. A groupname may not contain a
- colon (<code>:</code>). You may use a hyphen (<code>-</code>) if you don't
- want to assign the user to a group, but fill in the comment field.
- Additionally when using the <code>update</code> command, a period
- (<code>.</code>) keeps the original groups untouched.</dd>
-
- <dt><code><var>comment</var></code></dt>
- <dd>This is the place for your opaque comments about the user, like
- realname, mailaddress or such things. The server will ignore this
- field.</dd>
- </dl>
-
- <section id="options.encodings"><title>Encodings</title>
- <dl>
- <dt><code>-d</code></dt>
- <dd>crypt encryption (default, except on Win32, Netware)</dd>
-
- <dt><code>-m</code></dt>
- <dd>MD5 encryption (default on Win32, Netware)</dd>
-
- <dt><code>-s</code></dt>
- <dd>SHA1 encryption</dd>
-
- <dt><code>-p</code></dt>
- <dd>plaintext (<em>not recommended</em>)</dd>
- </dl>
- </section>
-
- <section id="options.commands"><title>Commands</title>
- <dl>
- <dt><code>add</code></dt>
- <dd>Adds an entry for <var>username</var> to <var>filename</var> using the
- encrypted password <var>encpasswd</var>.</dd>
-
- <dt><code>adduser</code></dt>
- <dd>Asks for a password and then adds an entry for <var>username</var> to
- <var>filename</var>.</dd>
-
- <dt><code>check</code></dt>
- <dd>Asks for a password and then checks if <var>username</var> is in
- <var>filename</var> and if it's password matches the specified one.</dd>
-
- <dt><code>delete</code></dt>
- <dd>Deletes the <var>username</var> entry from <var>filename</var>.</dd>
-
- <dt><code>import</code></dt>
- <dd>Reads <code><var>username</var>:<var>password</var></code> entries
- (one per line) from <code>STDIN</code> and adds them to
- <var>filename</var>. The passwords already have to be crypted.</dd>
-
- <dt><code>update</code></dt>
- <dd>Same as the <code>adduser</code> command, except that it makes
- sure <var>username</var> already exists in <var>filename</var>.</dd>
-
- <dt><code>view</code></dt>
- <dd>Just displays the contents of the DBM file. If you specify a
- <var>username</var>, it displays the particular record only.</dd>
- </dl>
- </section>
- </section>
-
- <section id="bugs"><title>Bugs</title>
- <p>One should be aware that there are a number of different DBM file formats
- in existence, and with all likelihood, libraries for more than one format
- may exist on your system. The three primary examples are SDBM, NDBM, the GNU
- project's GDBM, and Berkeley DB 2. Unfortunately, all these libraries use
- different file formats, and you must make sure that the file format used
- by <var>filename</var> is the same format that <code>dbmmanage</code>
- expects to see. <code>dbmmanage</code> currently has no way of determining
- what type of DBM file it is looking at. If used against the wrong format,
- will simply return nothing, or may create a different DBM file with a
- different name, or at worst, it may corrupt the DBM file if you were
- attempting to write to it.</p>
-
- <p><code>dbmmanage</code> has a list of DBM format preferences, defined by
- the <code>@AnyDBM::ISA</code> array near the beginning of the program. Since
- we prefer the Berkeley DB 2 file format, the order in which
- <code>dbmmanage</code> will look for system libraries is Berkeley DB 2,
- then NDBM, then GDBM and then SDBM. The first library found will be the
- library <code>dbmmanage</code> will attempt to use for all DBM file
- transactions. This ordering is slightly different than the standard
- <code>@AnyDBM::ISA</code> ordering in Perl, as well as the ordering used by
- the simple <code>dbmopen()</code> call in Perl, so if you use any other
- utilities to manage your DBM files, they must also follow this preference
- ordering. Similar care must be taken if using programs in other languages,
- like C, to access these files.</p>
-
- <p>One can usually use the <code>file</code> program supplied with most
- Unix systems to see what format a DBM file is in.</p>
- </section>
-
- </manualpage>
-